### AWS credentials

AWS credentials can be provided on a per-source basis via the standard AWS credentials provider chain:

1. Statically provided as part of the `WITH` block in source declaration. These credentials will be
   written to disk in plain text as well as being easily exposed via introspection commands and so
   this technique is only recommended for experimentation and development.
2. Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
   [`AWS_WEB_IDENTITY_TOKEN_FILE`][web-identity], and [many more][env-vars].
3. `credential_process` command in the AWS config file, by default located at `~/.aws/config`.
4. AWS credentials file and profile files. By default located at `~/.aws/config` and
   `~/.aws/credentials`, respectively.
5. The [IAM instance profile][instance-profile] provided by the Instance Metadata Service. This
   will only work if running on an EC2 instance with an instance profile.

*Changed in v0.10.0:* Materialize supports the standard AWS credentials provider
chain as described above. Previously Materialize had support for only an
unspecified subset of the standard credentials provider chain.

#### AWS credentials `WITH` options

Static credentials can be configured by the following `WITH` options:

Field | Value type | Description
----- | ---------- | -----------
`access_key_id` | `text` | A valid [access key ID][access] for the AWS resource.
`secret_access_key` | `text` | A valid [secret access key][access] for the AWS resource.
`token` (optional) | `text` | The session token associated with the credentials, if the credentials are temporary

Alternatively, you can specify a [named config profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) to assume. This named profile must exist within the AWS `credentials` or `config` file.

Field | Value type | Description
-----|------------|------------
`profile` | `text` | An AWS config profile to assume. *New in v0.20.0.*

The following `WITH` options can be set with either static credentials, a profile, or alone depending on the environment for credentials.

Field | Value type | Description
------|-----------|------------
`role_arn` | `text` | An IAM role to assume. *New in v0.20.0.*
`region` | `text` | The region to use for all AWS requests.

Credentials fetched from a container or instance profile expire on a fixed
schedule. Materialize will attempt to refresh the credentials automatically
before they expire, but the source will become inoperable if the refresh
operation fails.

[web-identity]: https://docs.rs/aws-config/latest/aws_config/web_identity_token/index.html
[env-vars]: https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html
[access]: https://docs.aws.amazon.com/streams/latest/dev/controlling-access.html
[instance-profile]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
